@ Apple Lisa Computer Information * Lisa Memory Management Memo (Malloy * Nov 1980) 


November 7, 19780 
Ta: Lisa Seftware 
ec: Cauch, Smith 
From: Tom Malloy 


Subyect: Interface Specification for the standard storage manager 


Several weeks ago we discussed the advantages of a unified intra-segment 
storage management strategy. At that time I proposed we adopt the Lotus 
storage manager, ar some variation thereof, as the standard. This met with 
some approval. Attached is an intefface specification for 

the storage manager we discussed. Please read and comment copiously an 
content and style. 


It seems unavoidable to have two memory managers; this intra-segmant 

manager and the OS’ real-memory/segment manager. While twa is not as goad 

as one it is certainly much better than one per application. Between these 
two pieces of saftware it would be nice (and I think it is very possible) to 
satisfy most/all af our memory management needs. T& we have almast satisfied 
your needs, but not quite, lets get together and talk — maybe we can enhance 
one or both of the memory managers to avoid the need for another one. 


Thanks - Tom 
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Preliminary Interface Specification — UnitHz @ 


I. Introduction 


UnitHz performs intra-segment memory management for Latus, LisaCalc, 

the Window Manager (Lily) and portions of the Operating System and Pascal 

runw~time. UnitHz provides a layered implementation of “heap-like" storage 

regions, called zanes. The most basic layer provides allocation - 

and deallocation of non-relocatable blacks of storage within the zone. 

This is. in the parlance of Pascal, "a Pascal heap with NEW and DISPOSE". 

At the second level, code is added to provide relocatable storage block 

management: a campacting heap. Since this relocation ability is outside 

the gomain of knowledge of both the hardware and the program development 

environment, certain conventions mugt be obeyed by the programmer when 

using this storage mechanism. Failure to follow the conventions will 

usually produce catastrophic side effects. This potential drop in 

reliability should be weighed against the added flexibility when 

choosing a storage management methodology. Finally, a third level 

of code implements a primitive, object oriented virtual memory. Lotus 

is the only known client of this interface. Storage blocks managed 
UnitHz have a maximum size of 32k bytes. The zones themselves may 


arbitrarily large. 
ITC ¢/200/: See Faure i p. 6 


TI. Nependencies 


UnitHz imports. UnitStd to provide a set of very common type declarations not 
re-defined by Pascal. For instance the type, TP, is a pointer to 
undescriminated storage (i.e. compatible with any pointer). ‘Similarly there 
are standard type declarations for arrays of bytes, arrays of characters and 
other low level primitives. UnitStd also defines primitive operations an 
these types, such as the maximum and minimum of two integers (CMax and CMax). 


III. Key objects 


The key exported obyects of UnitHz are the handles om the storage blocks of 
various types. In particular: 


p undescriminated pointer. The handle on a non-relocatable 
block of storage is ap. 


a pointer to ap. This double indirect pointer is the 
handle on a relocatable black of storage. The h is 
invariant with respect to compaction of the zone. The 
pointer, h*, is not. The cenventions concerning the 

use of the compacting allocator deal with the circumstances 
under which these handles can be dereferenced. The 
dereferencing rule, in its simplist form states that 

all dereferenced handles become invalid upon the execution 
of any procedure in the UnitHz interface. <A more practical 
corollary states that any procedure call of unknown effect 
may invalidate the handles. This includes all external 
procedures. In practice, Lotus implementors typically 
consider dereferenced handles invalid after any procedure 
call, internal or external. 


~The handle. h, points at a single, unique pointer ta the — 
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block itself. The black, in turn, contains encugh information 
to locate this pointer when the compactor wishes to relocate 
it. The pointer must be in a static location. In particular, 
it cannot be embedded in a relocatable block. 
‘ 
name. A Ga2-bit (mostly?) uninterpreted handle on a swappable 
obyect. Access to swappable objects is via a procedural inter? 
which maps the name through a hash table which identifies 
all of the currently resident, swappable objects. If the objec 
is is not resident. a user definable Ptpap" routine is invoked 
to read it into the cache. The particulars af this interface 
will remain vague at least until we design the procedure 
variable scheme. 


TV. ° Secondary objects 

a 
UnitHz manages a collection of storage zones (ahz’s). A storage zane is a 
cantiguous block of memory. It is expected that most zones will be the 
complete contents of hardware data segments, although this is nat a 
requirement. A storage zone is divided into a header. describing the 
contents of the zone, followed by a sequence of storage blocks (abk‘s). 
A tone has a type, tyhz, which determines the kind of blocks the zone 
might contain. We currently imagine four types of blocks: 


1) Free blocks 

2) Non-relocatable blocks 
3) Relocatable blocks 

4) Named blocks 


It does nat seem to make sense to have all of these in a single zone. 

For instance, it has not been decided whether allowing the mixture af 
Telocatable and non-relocatable blocks in the same zone would be a feature or 
headache, although it is technically feasible. Let’s say for discussion’s 
sake that there are two types of zones: 


tyhzNrel non-relacatable blocks only 
tyhzRel relocatable and swappable blocks anly 


Each block has a header followed by the user’s storage. The header contains 
a 2-bit block type field, tybk, a 14-bit count of words: cw, and some tybk depe 
information. Figure 1 illustrates the layout of a zone. 


The type dependent information is: 


1) Free blocks are linked together on a doubly linked list used by the 
allocation routines. 


. Non—relocatable blocks have no type dependent nfornerton and hence 
the smallest per block overhead (146-bits) 


Relocatable blocks have a 16 bit “lecator" of the single pointer to the 
black. This single pointer, which is pointed AT by the handle, h, can be 
in ane of two general areas. Most of these pointer will be in a pool of 
pointers at the beginning of the zone, in which case the locator is an 
offset from hz to the pointer. When the zone is initialized the user may 
supply another base address, pBase. This is provided to allow the user to 
place block pointers in his global data area. Any call to allocate-a block 
must supply a handle which points at a location within 32k bytes of pBase 
or hz. ~~ 
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4) Named blocks contain the 32-bit name which identifies the black plus ® 
same miscellaneaus information about the obsect. For instance, there 
is a small LRYV timer used by the software to 
choose a block to remove from the cache. 


V. Initialization, reconfiguaration and destruction of objects 
HzInit(pFst. phim, ipPoolMac, logIpnlLim, pBase) : hz 


The contiguous block of storage IN CpFst..plLim) is turned into a zone. If 
ipPoolMac > 0 then a pool of pointers is allocated at the beginning of the 
zone. These pointers will point at relocatable blocks, therefore the address 
of each pointer is potentially an h-type handle. A hash table large enough to 
held 2*“logiIpnlLim pointers is allocated as a relocatable block in the zrone. A 
handle on the zone is returned. We can imagine dynamically increasing 

ar decreasing ipPoolMac and ipnLim, but the current implementation does not 
include this feature. 


A zone which contains no user data can be abandoned at any time by the user 
without notifying UnitHz. : 


~ 


VI. Operation 
IMPLEMENTATION NOTE: 


In order to allow for multiple zones each routine in the implementation 

must take the zone handle, hz, 48 an argument. This may be viewed, with 

some justification, as a high price to pay. A subtle implementation decision 
was made in order to minimize this overhead in the future. Namely, the zone 
pointer is always the first parameter to the procedure. If and when the 

Pascal run=time conventions are changed to pass procedure parameters in register 
this could have the very pleasant effect of the zone handle being placed in 

an address register when an interface pracedure is called and remaining there 
for the duration af its execution. This canvention may be of use to other 
programmers implementing “obyect oriented" interfaces. 


AllocateBk(hz, ADst, cb, tybk) 


Allocates a block of type tybk with cb bytes af user storage in zone hz. 
A pointer to the user’s portion of the block is placed in hDst*. 


HAllocatethz, cb) : hRslt 

Allocates a relocatable block with cb bytes af user storage in zone hz. 

& pointer to the block is allocated from the paocl and its address returned 
at the result. 


FreeBk(hz, hDst, tybk) 


Frees the block refered to by hDst. 


ChangeSizeH( hz, hDst. cbhNew) 


Changes the size of a relocatable block refered to by hNst. Bad news if 
it is not.a relocatable block. . 
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PMapNibz, nm, flock) : p : 13) 


Maps the name, n, through the hash table of resident named objects. If it 

sis found a pointer to the user portion of that block is returned. Otherwise, 
Chand waved the user-defined “trap" mechanism is invoked to read it inta the 
zene. flock is a flag. If true the object is Locked into physical memory 
until unlocked by another call on PMapN with the same n and flock = FALSE. 
Without this extra feature it would be technically impossible to “dereference” 


two named objects simultaneously, since the second cald might invalidate the 
first painter. . 


SetFDirty (hz, nn, fNirty) 


Sets the dirty flag for the object named by no. 


When the obyect is swapped 
aut it will be updated on the disk. 


a 
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